STAC Search Endpoint

The STAC Search endpoint enables querying imagery and metadata using filters like bounding box, datetime range, collections, or item IDs.

This endpoint supports pagination, sorting, and advanced filtering making it ideal for dynamic, complex queries.

Endpoint

POST /public/stac/search

Include the following header:

x-api-key: YOUR_API_KEY

Example Request (cURL)

curl -X POST "https://giq.ae/public/stac/search" \
  -H "accept: application/geo+json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "bbox": [54.4, 24.3, 54.5, 24.5],
    "collections": ["d98629ef-58c5-9af8-714c-ac86b03fba66"],
    "datetime": "2024-01-01T00:00:00Z/2024-12-31T23:59:59Z",
    "limit": 10,
    "offset": 0,
    "sortby": [
      { "field": "properties.datetime", "direction": "desc" }
    ]
  }'

Example Response (Sample):

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "BSG-73-20240830-102222-194727757-ortho.zip",
      "title": "28658e5f-6b73-11ef-812d-19f768344900",
      "collection": "6e68aecb-0d12-11d5-bb28-35121ad19238",
      "geometry": {
        "coordinates": [
          [
            [54.4062737, 24.466125],
            [54.4062737, 24.3901998],
            [54.4880255, 24.3901998],
            [54.4880255, 24.466125],
            [54.4062737, 24.466125]
          ]
        ],
        "type": "Polygon"
      },
      "bbox": [54.4062737, 24.3901998, 54.4880255, 24.466125],
      "properties": {
        "datetime": "2024-08-30T10:22:22.004Z",
        "name": "BSG-73-20240830-102222-194727757-ortho.zip",
        "giq:layer_type": "RASTER",
        "description": null,
        "giq:ingestion_date": "2024-09-05T10:39:27Z",
        "source_type": "MULTISPECTRAL",
        "giq:source": "BLACKSKY",
        "giq:source_type": "MULTISPECTRAL",
        "giq:source_sub_type": "DEFAULT",
        "layer_type": "RASTER"
      },
      "assets": {
        "rendered_preview": {
          "href": "https://giq.ae/api/map/preview?bbox=54.4062737,24.3901998,54.4880255,24.466125&sourceId=28658e5f-6b73-11ef-812d-19f768344900&width=160&height=160",
          "title": "Rendered preview",
          "type": "image/png",
          "roles": ["overview"]
        },
        "data": {
          "href": "https://minio.giq.ae/.../BSG-73-20240830-102222-194727757-ortho.zip?...",
          "title": "Source File",
          "type": "application/zip",
          "roles": ["data"]
        }
      },
      "links": [
        {
          "rel": "self",
          "href": "https://giq.ae/public/stac/collections/6e68aecb-0d12-11d5-bb28-35121ad19238/items/28658e5f-6b73-11ef-812d-19f768344900",
          "type": "application/geo+json",
          "title": "STAC Item",
          "method": "GET"
        },
        {
          "rel": "collection",
          "href": "https://giq.ae/public/stac/collections/6e68aecb-0d12-11d5-bb28-35121ad19238",
          "type": "application/json",
          "title": "STAC Collection",
          "method": "GET"
        },
        {
          "rel": "root",
          "href": "https://giq.ae/public/stac/",
          "type": "application/json",
          "title": "STAC Root Catalog",
          "method": "GET"
        },
        {
          "rel": "preview",
          "href": "https://giq.ae/api/map/preview?bbox=54.4062737,24.3901998,54.4880255,24.466125&sourceId=28658e5f-6b73-11ef-812d-19f768344900&width=60&height=60",
          "type": "text/html",
          "title": "Map of item",
          "method": "GET"
        }
      ],
      "stac_version": "1.0.0",
      "stac_extensions": [
        "https://stac-extensions.github.io/view/v1.0.0/schema.json",
        "https://stac-extensions.github.io/sar/v1.2.0/schema.json"
      ]
    }
  ],
  "numberMatched": 324,
  "numberReturned": 10,
  "limit": 10,
  "offset": 0,
  "sortby": [
    {
      "field": "properties.datetime",
      "direction": "desc"
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "/public/stac/search?limit=10&offset=0",
      "type": "application/geo+json",
      "title": "Current page",
      "method": "GET"
    }
  ]
}

Response Overview

Returns a filtered list of STAC Items matching the criteria specified in the request. Useful for exploring large catalogs or narrowing results by bounding box, datetime, or collection.

Request Parameters

Parameter	Required	Type	Description
bbox	Yes	Array\[4]	[west, south, east, north] in WGS84 coordinate reference system
collections	Yes	Array	List of STAC Collection IDs to filter (e.g., ["blacksky"])
datetime	Yes	String	ISO 8601 interval string (e.g., "2024-01-01T00:00:00Z/2024-12-31T23:59:59Z")
limit	No	Integer	Maximum number of results to return (e.g., 10)
offset	No	Integer	Number of items to skip (used for pagination)
sortby	No	Array	Sort rules (e.g., [ { "field": "properties.datetime", "direction": "desc" } ])

Response Fields

Field	Description
type	Always FeatureCollection
features	Array of STAC Item objects that match the query criteria
numberMatched	Total number of results that match the search query
numberReturned	Number of features included in the current response page
limit	The limit value used in the query (if provided)
offset	The offset value used in the query (if provided)
sortby	Sorting parameters applied in the query
links	Array of pagination and navigation links

Let me know if you'd like to append this directly to the /public/stac/search documentation section or export as Markdown separately.

Response Links

Rel	Description	URL Template
self	Link to the search result page	/public/stac/search
collection	Link back to parent collection	/public/stac/collections/{id}

Assets

Key	Description	Type
rendered\_preview	Preview image of the raster	image/png
data	Downloadable ZIP of geospatial dataset	application/zip

Use Cases

• Search satellite imagery within a custom AOI and time window
• Paginate results for large-scale catalog browsing
• Integrate STAC queries into dashboards or processing pipelines
• Combine filters to automate discovery of new assets